ParcelAddress API

(0 reviews)

Collection Locations

Resource URL

UAT:

http://api.uat.nzpost.co.nz/parceladdress/2.0/domestic/pcdlocations
Production:
https://api.nzpost.co.nz/parceladdress/2.0/domestic/pcdlocations

Resource Description

Returns a list of parcel collection points nearest to the coordinates provided.

Resource Information

AttributeDetail
Response FormatJSON
Requires AuthenticationYes
Rate Limited15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

Please note that all request parameters should be in lower case.

Request Parameters

Field NameDescriptionMandExample
latitudeThe latitude of the delivery address. This value is returned from the Get Address Details resource. The results returned are ordered by increasing distance from the supplied coordinates.Yes-41.288719
longitudeThe latitude of the delivery address. This value is returned from the Get Address Details resource. The results returned are ordered by increasing distance from the supplied coordinates.Yes174.775019
countLimits the number of results return to this number.Yes5

Sample Request

https://api.nzpost.co.nz/parceladdress/2.0/domestic/pcdlocations?latitude=-39.939946&longitude=175.076388&count=5

Business Rules

The following business rules are applied on each /addresses request:

NameDescription
BR001There is no maximum value for count but you should consider the impacts of displaying a large number of results in your user interface
BR002The latitude and longitude provided in the request are validated to ensure only numbers are submitted but are not validated as being coordinates within New Zealand
BR003If the delivery address used on a label is an NZ Post collection point, then you MUST create a PCD type subscription for the parcel recipient via the ParcelNotification API. This requires the tracking reference from the label, parcel recipient's first and last names, email address and the location ID of the collection point.

Response Parameters

The following lists the required fields in the /addresses response message.

Field NameDescriptionMandExample
successReturns if request is successfulYestrue
locationsContains array of collection location objects. The number of objects will not exceed the โ€˜countโ€™ value defined.Y if success = trueSee Locations Object Parameters
message_idA unique id for the API callYesd413cb59-9aab-48a3-bdd9-7d62ecf9027c

Locations Object Parameters

The following lists the fields in the locations object.

Field NameDescriptionMandExample
company_nameName of the company hosting the collection pointYesWanganui CourierPost Depot
latLatitude of the collection PointYes-39.933741
lngLongitude of the collection PointYes175.046749
phoneContact phone number for the collection pointYes0800 268 7437
distance_in_mDistance in metres (as the crow flies) from the coordinates provided to the collection pointYes1500
full_addressHuman readable street address for the collection pointYes62 Wilson Street, Wanganui 4500
idLocation ID for the collection pointYes99061
hoursArray listing the openin and closing hours of the collection point for each day of the weekYesSee Hours Array Parameters

Hours Array Parameters

The following lists the fields in the hours object.

Field NameDescriptionMandExample
dayIndicates the day of the week where 0 = Sunday through 6 = SaturdayYes2
openTime of opening for day indicated in day parameter using 24 hour clockNo08:00
closedTime of closing for day indicated in day parameter using 24 hour clock. If location not open, then parameter set to 'true'.Yes17:30

Error Response Elements

Field NameDescriptionMandExample
successReturns if request is successfulYesfalse
errorsError object with error detailsY if success =falseSee Error Object Parameters below
message_idThe unique message identifierYesec608f40-2a8b-11e5-a9c0-025c481d35ef

Error Object Parameters

Field NameDescriptionExample
codeError code where first 3 digits are http status code, last three digits identify error type400002
messageDescription of error codeInvalid Parameter(s)
detailsDescription of specific errorLatitude cannot be null.

HTTP Status Codes

Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request

CodeMessage
200Success
400Bad request
401Unauthorized
403Forbidden
409Invalid request
500System unavailable

Error Codes

CodeMessage
200001Partial results returned, not all system(s) have responded
200002All sources responded, data may be incomplete
400001Parameter(s) missing
400002Invalid parameter(s)
400003Non mutually exclusive parameters detected
401001Unauthorised access, please contact administrator
500001General Exception
500002System(s) offline

Sample Response

Success Sample:


{
    "success": true,
    "locations": [
        {
            "company_name": "Wanganui CourierPost Depot",
            "lat": -39.933741,
            "lng": 175.046749,
            "phone": "0800 268 7437",
            "full_address": "62 Wilson Street, Wanganui 4500",
            "id": 99061,
            "hours": [
                {
                    "day": 0,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 1,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 2,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 3,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 4,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 5,
                    "open": "09:00",
                    "close": "12:30"
                },
                {
                    "day": 6,
                    "closed": true
                }
            ],
            "distance_in_m": 2619,
            "address_details": {
                "address_line_1": "62 Wilson Street",
                "suburb": "Wanganui",
                "city": "Wanganui",
                "post_code": "4500"
            }
        },
        {
            "company_name": "Palmerston North CourierPost Depot",
            "lat": -40.32668,
            "lng": 175.619298,
            "phone": "0800 268 7437",
            "full_address": "99 McGregor Street, Milson, Palmerston North 4414",
            "id": 99060,
            "hours": [
                {
                    "day": 0,
                    "open": "08:00",
                    "close": "18:00"
                },
                {
                    "day": 1,
                    "open": "08:00",
                    "close": "18:00"
                },
                {
                    "day": 2,
                    "open": "08:00",
                    "close": "18:00"
                },
                {
                    "day": 3,
                    "open": "08:00",
                    "close": "18:00"
                },
                {
                    "day": 4,
                    "open": "08:00",
                    "close": "18:00"
                },
                {
                    "day": 5,
                    "open": "08:00",
                    "close": "12:00"
                },
                {
                    "day": 6,
                    "closed": true
                }
            ],
            "distance_in_m": 63083,
            "address_details": {
                "address_line_1": "99 McGregor Street",
                "suburb": "Milson",
                "city": "Palmerston North",
                "post_code": "4414"
            }
        },
        {
            "company_name": "Merrilands Lotto and Post",
            "lat": -39.066579,
            "lng": 174.102856,
            "phone": "06 758 0753",
            "full_address": "200 Mangorei Road, Merrilands, New Plymouth 4312",
            "id": 72366,
            "hours": [
                {
                    "day": 0,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 1,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 2,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 3,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 4,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 5,
                    "closed": true
                },
                {
                    "day": 6,
                    "closed": true
                }
            ],
            "distance_in_m": 128090,
            "address_details": {
                "address_line_1": "200 Mangorei Road",
                "suburb": "Merrilands",
                "city": "New Plymouth",
                "post_code": "4312"
            }
        },
        {
            "company_name": "Bell Block Lotto and Book Centre",
            "lat": -39.035667,
            "lng": 174.142533,
            "phone": "06 755 1038",
            "full_address": "7 Bell Block Court, Bell Block, New Plymouth 4312",
            "id": 72128,
            "hours": [
                {
                    "day": 0,
                    "open": "08:30",
                    "close": "17:30"
                },
                {
                    "day": 1,
                    "open": "08:30",
                    "close": "17:30"
                },
                {
                    "day": 2,
                    "open": "08:30",
                    "close": "18:30"
                },
                {
                    "day": 3,
                    "open": "08:30",
                    "close": "17:30"
                },
                {
                    "day": 4,
                    "open": "08:30",
                    "close": "17:30"
                },
                {
                    "day": 5,
                    "open": "08:30",
                    "close": "19:00"
                },
                {
                    "day": 6,
                    "closed": true
                }
            ],
            "distance_in_m": 128578,
            "address_details": {
                "address_line_1": "7 Bell Block Court",
                "suburb": "Bell Block",
                "city": "New Plymouth",
                "post_code": "4312"
            }
        },
        {
            "company_name": "New Plymouth CourierPost Depot",
            "lat": -39.048723,
            "lng": 174.109921,
            "phone": "0800 268 7437",
            "full_address": "2 Smart Road, Waiwhakaiho, New Plymouth 4312",
            "id": 99066,
            "hours": [
                {
                    "day": 0,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 1,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 2,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 3,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 4,
                    "open": "08:00",
                    "close": "17:30"
                },
                {
                    "day": 5,
                    "open": "08:00",
                    "close": "11:00"
                },
                {
                    "day": 6,
                    "closed": true
                }
            ],
            "distance_in_m": 129219,
            "address_details": {
                "address_line_1": "2 Smart Road",
                "suburb": "Waiwhakaiho",
                "city": "New Plymouth",
                "post_code": "4312"
            }
        }
    ],
    "message_id": "d413cb59-9aab-48a3-bdd9-7d62ecf9027c"
}

Failure Sample:


{
   "success": false,
   "errors": [   {
      "code": "400002",
      "message": "Invalid parameter(s)",
      "details": "Latitude cannot be null."
   }],
   "message_id": "28eed9bd-8ea5-4167-85d8-a20d4a5e7a42"
}

Reviews